Amend

The Amend command(s) is designed to allow modification of model predictions during any simulation cycle. Modifications can include changes to DBH increment, height increment, height, and mortality rate. Top kill can also be scheduled on trees using similar statements.

Amendment commands can be used to model natural disturbance impacts or introduce climate change effects on growth and mortality responses. For example, mortality could be increased for a fixed period of time for balsam fir as a result of insect attack. Or growth could be increased over time as a result of global warming.

They can also be used to modify predictions following different stand prescriptions, where resulting stand dynamics are not well represented by the underlying stand model. For example, you could use these commands to increase the DBH increment of crop trees following thinning for a certain period of time, if field observations suggest a larger DBH growth response should occur than predicted by the current DBH increment model.

And finally, if field observations suggest that the model performs poorly in certain contexts, then these statements can be used to temporarily fix unrealistic model behaviour until such issues can be properly resolved in the underlying model. The OSM Simulation.Model.Calibrator can automatically generate AMEND commands for you from local diameter growth or local height growth observations.

Actions

def MyExampleAction

Amend {cycle delay}

{Tree-level growth and mortality modifier statements…}

See Actions for information about cycle delay arguments in the example above.

Prediction modifications are made after all Variant predictions. This prevents indirect influence of one modification (e.g., diameter growth) on other Variant models (e.g., height growth, mortality). The one exception to this rule is modification to tree height predictions on trees missing heights. Missing tree heights are always predicted:

1) before the simulation starts (cycle 0) or

2) at the end of each simulation cycle for new trees (recruits) with missing heights.

For the first case, modification to tree heights predicted for missing trees may influence Variant model predictions if they depend on tree height. For the second case, new trees (recruits) added during the current cycle do not experience growth or mortality until the following cycle so growth, mortality, and top kill modifications have no effect on these trees. If the recruit is lacking height, its height is predicted (with any user modifications considered) and assigned immediately before the end of the current simulation cycle and before adding the recruit to the tree list.

Modifier statements

The following Amend variables are used to modify tree growth, mortality, or height for trees contained in the current tree list. Usage is described below.

Variable	Metric	USA	Description
DBHI	cm/yr	inches/yr	Annual tree DBH increment predicted for the current cycle. DBHI is limited between 0 and the maximum DBHI defined for the species by the Variant.
HTI	m/yr	feet/yr	Annual tree height increment predicted for the current cycle. HTI is limited between 0 and the maximum HTI defined for the species by the Variant. To reduce height for tree top kill, see HTK below.
MR	ratio	ratio	Annual tree mortality rate or probability predicted for the current cycle. MR is limited between 0 and 1. When mortality is deterministic (Model.IsRandom = FALSE), the probability of mortality is assigned to the tree as a continuous rate. Because mortality rate (probability) is a continuous value ranging between 0 and 1, linearly adjusting it has predictable consequences. However, if tree mortality is random, individual tree records with less than one stem/hectare will be assigned a mortality rate (MR) of either a 0 or 1 (MR=100% mortality) by the model. This is important to understand when adjusting MR as outcomes can be unexpected and often unpredictable. It is therefore advisable to make mortality deterministic when adjusting mortality.
HT	m	feet	Tree height predicted for a tree with a missing height when loading trees or at the end of the current cycle for a new tree (recruit) with no height.
HTK	m	feet	Height of tree with top kill (HTK) is equivalent to tree height at beginning of current cycle. To induce tree top kill, simply reduce HTK. The function must result in a reduction in tree height; for example, HTK * 50% will reduce tree live height by 50%. Note that this function schedules tree top kill; it does not immediately result in tree top kill. OSM activates tree top kill after all predictions and amendments have been set. If tree height is reduced, no height growth (HTI) is applied for the current cycle.

Amendments can either be applied to all trees or applied to certain species, species groups, and/or tree sizes. The following examples are provided to show how mortality or growth can be increased or reduced for specific trees. There is no limit on the number of these statements that could be stated under the Amend command.

Amend

# Increase DBH increment per year by 40%

# in all spruce (species group) trees

DBHI * 40% in Spruce

# Increase spruce height predictions by 20% for missing tree heights

# Reduce hardwood height predictions by 7.7% for missing tree heights

HT * 120% in Spruce

HT * 92.3% in Hardwood 

# Reduce predicted height increment per year by 0.1 m/yr

# in all hardwood (species group)

HTI – 0.1 in Hardwood 

# Add 0.5 to predicted mortality probability (ratio) in all

# balsam fir (BF) with DBH >= 24.5 cm

MR + 50% in BF with DBH >= 24.5

# Limit DBH increment to a maximum of 1.5 cm/yr

# for all trees with a height greater than 20 m

DBHI <= 1.5 with HT > 20

# Bound DBH increment to between 0.5 and 1.5 cm/yr

# for all trees with DBH between 20 and 30 cm

DBHI 0.5 1.5 with DBH 20 30

Note above and in the table below that a number of mathematical operators are provided to determine whether your modifier should be added, subtracted, or multiplied against the tree measure you want to modify. In addition, a number of equality operators can be used to bound predictions that may have been found to perform poorly in certain contexts.

Operator	Result
*	Tree Rate = Predicted Rate * Modifier
+	Tree Rate = Predicted Rate + Modifier
-	Tree Rate = Predicted Rate - Modifier
>=	Tree Rate = Max(Predicted Rate, Modifier)
<=	Tree Rate = Min(Predicted Rate, Modifier)
=	Tree Rate = Modifier

See conditional statement documentation regarding formulation of IN and WITH conditions.

Scheduling modifications

OPERABLE statements can be used in combination with AMEND statements in ACTIONS declarations to define what cycle, stand age, year, and/or stand structural or compositional conditions must exist before the modifications should begin. See OPERABLE for examples. Once an action becomes activated, cycle arguments following the AMEND statement determine the cycles (relative to activation cycle) the modifications should be applied in. If no arguments are provided, then the modifications will occur immediately, but will be limited to the current cycle.

In the example below, this action will be activated (become operable) in cycle 3. The AMEND arguments 1..10 state that modifications are not to begin until one cycle after activation and are to end after cycle 10. Multiple AMEND standment groups can be used in a single action to schedule different modifications for different cycles. The AMEND statement, like the OPERABLE statement, can state multiple cycles (1 2 3 4 5 7 8 9) or cycle windows (1..5 7..9) as cycle arguments; however, unlike the OPERABLE statement, the cycles are relative to the activation cycle.

ACTIONS

def MyCalibrationAdjustment

OPERABLE 3

AMEND 1..10

DBHI * 40% in Spruce

BLENDing modifications with Variant predictions

Modifications, once scheduled, can be increasingly diluted over time with Variant predictions by using the BLEND command. Blending predictions is especially useful for modeling thinning growth response effects, where an immediate growth response is anticipated which then diminishes over time.

The BLEND command has two required arguments:

1) blendCycle specifies the cycle to begin blending modified predictions with base predictions.

2) endCycle specifies the simulation cycle to revert back to base predictions.

Weight of modified predictions decline linearly in each cycle from 100% at the blendCycle down to 0% by the endCycle.

ACTIONS

def MyCalibrationAdjustment

OPERABLE

Age = 20

AMEND 1 2 5..10

BLEND 5 10

DBHI * 120% in Spruce

The example above states that amendments to Variant DBHI predictions should be activated (become operable) when stand age equals 20. Let’s assume the stand reaches age 20 by simulation cycle 8. In that case, amendments will be scheduled for cycle 9, 10, and between cycles 13 and 17. Note that AMEND statement cycles 1, 2, and 5…10 are relative cycle arguments and must be added to the cycle number the action was activated in (cycle 8). Modified predictions will begin blending with base predictions in cycle 13 (relative cycle 5). By cycle 17 (relative cycle 10), DBHI will be based 100% on Variant predictions. This example is probably a bit absurd in terms of cycle arguments, but is designed to demonstrate a few different cycle argument formulations possible.

Probabilistic modifiers

In some cases, often for natural disturbance modelling, you may wish to add an error term to your modifier so that not all trees receive exactly the same modification. Also you may want to make the modification itself a probabilistic event.

The Error command can be used to randomly select modifiers from a normal (Gaussian) distribution. The modifier value is the mean of this distribution and Error value assigned is one standard deviation from the mean value. The error value assigned must be in the same units as the modifier value. If the Error command is used, then for each tree, a random modifier value is selected from the normal distribution of modifier values.

The Prob command can be used to make the modification a probabilistic event. For example, if the probability of tree top kill is 50% following an insect outbreak, then we would only want tree top kill to occur on 50% of the host trees. However, because an OSM tree record cannot be partitioned, if the probabilistic event occurs, the event is applied to the entire tree record (with tree expansion factor) Therefore, some caution is required when using this command on stands with many trees and few tree records.

Examples:

# Increase mortality rate by 15% ± 5% standard deviation

# for balsam fir (BF) with DBH >= 24.5 cm

MR * 115% in BF with DBH >= 24.5

Error 5%

# Induce top kill on 20% of

# balsam fir (BF) trees with HT >= 10 cm

# For trees that get top killed,

# reduce live height by 70% ± 10% standard deviation

HTK * 70% in BF with HT >= 10

Error 10%

Prob 20%

Using equations in modifier statements

Simple linear equations can be used to make modifications a function of the prediction, DBH, basal area of larger trees (BAL), and/or stand basal area (StandBA).

Note that the complexity of these linear equations is quite limited. This basic functionality was developed to support calibrated models generated by the OSM Calibrator. The only mathematical operators supported are +, -, and *. The equation must also be stated in a ridged format as:

Modifier = b₀*Intercept + b₁*x₁ + … + b_X*x_n

, where Modifier must be either DBHI, HTI, MR, HT, or HTK, b₀ is the intercept, b₁..b_n are coefficients for respective tree attribute variables or stand attribute variables x₁..x_n described in the table below. Only variables that you want to use in the equation need to be stated with coefficients. Any variable not stated in the equation, including the intercept, is assumed to have a coefficient value of zero.

Attribute Variable	Metric	Description
PREDICTION	*	Predicted value (DBHI, HTI, MR, HT, or HTK). See modifier descriptions in previous table for metric units. The “PREDICTION” variable name must be used in place of the actual modifier variable name on the right-hand side of the equation.
DBH	cm	DBH of tree at the beginning of the current cycle.
BAL	m^2/ha	Basal area of thicker trees after cut (if any).
StandBA	m^2/ha	Stand basal area of all trees after cut (if any), excluding recruits.

The example below demonstrates how one might use equations to modify DBH growth and mortality following an insect outbreak disturbance. Note that the equations used are absurd and only meant to demonstrate use of variables described above. The only change from Amend statement syntax described previously is that the right-hand side of the equation must be preceded by and equal operator and surrounded in double quotes as shown below. Constraints can be used to limit the modifications to certain tree species or sizes.

ACTIONS

def InsectOutbreak

OPERABLE 2

AMEND 0..4

BLEND 1 4

DBHI = "0.1+0.23*PREDICTION+0.00045*DBH" in SpruceFir with DBH >= 5

MR = "1*PREDICTION+0.0023*StandBA" in SpruceFir with DBH >= 5

Example decoded:

· OPERABLE 2 states that the outbreak should be activated in cycle 2.

· AMEND 0..4 states modifications should be applied between relative cycles 0 and 4, or actual cycles 2 and 6 (activated cycle + relative cycle).

· BLEND 1 4 states modified predictions should begin blending with base predictions one cycle after activation (100% modified predictions) and completely revert back to base predictions four cycles after activation (100% base predictions). At cycles 2 and 3, modified predictions will have respective weights of 66.6% and 33.3% compared to base prediction respective weights of 33.3% and 66.6%.

· Modifications to MR and DBHI are limited to Spruce and Fir (the species group ‘SpruceFir’ was user defined, but not shown) and to DBH > 5 cm.